Codecov Report

Merging #94 (ea773b7) into main (0812d5f) will not change coverage.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##              main       #94    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files            6         9     +3     
  Lines          468       820   +352     
  Branches        69       106    +37     
==========================================
+ Hits           468       820   +352     

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0812d5f...ea773b7. Read the comment docs.

Oh hey... look. We can't add the pytypes PR as a dependency because you can't use a non-pypi dependency in install_requires and released pytypes only supports up to 3.6. :]

• I'll start by writing it here, but presumably some form of this belongs in the docs.

I need a clearer presentation of the relational properties of the Registry idea. There are several entity categories: tag, field, class, hint. For each category C, I want a list of which of the others are required to retrieve a unique instance of C. For example, "a w is uniquely identifiable from a (x,z) tuple or a (y,z) tuple" where w,x,y,z are standing in for some of {tag,field,class,hint}.

P.S. A direct answer is at the end. This was a good refresher for myself and I leave it here in case it is useful. Copied here.

So I guess the summary of my self-reacquaintance with this code is that the present implementation in TypeAndHintFieldRegistry selects a field/tag pair based on a hint for serialization and for deserialization it takes a tag and selects a field.

It may be that this mechanism should have a higher level of formality, but I will start by trying to explain what is already here. I think the registry protocol describes the needed functionality and then we can move on to the provided implementation.

https://github.com/altendky/desert/blob/ea773b7bc7df6591ff7c0e538e2f96a11637657b/src/desert/_fields.py#L32-L61

class FieldRegistryProtocol(typing_extensions.Protocol):
    """This protocol encourages registries to provide a common interface.  The actual
    implementation of the mapping from objects to be serialized to their Marshmallow
    fields, and likewise from the serialized data, can take any form.
    """

    def register(
        self,
        hint: t.Any,
        tag: str,
        field: marshmallow.fields.Field,
    ) -> None:
        """Inform the registry of the relationship between the passed hint, tag, and
        field.
        """
        ...

    @property
    def from_object(self) -> "FromObjectProtocol":
        """This is a funny way of writing that the registry's `.from_object()` method
        should satisfy :class:`FromObjectProtocol`.
        """
        ...

    @property
    def from_tag(self) -> "FromTagProtocol":
        """This is a funny way of writing that the registry's `.from_tag()` method
        should satisfy :class:`FromTagProtocol`.
        """
        ...

(I wonder if I should (could?) make a function to create those protocol-conforming methods...)

https://github.com/altendky/desert/blob/ea773b7bc7df6591ff7c0e538e2f96a11637657b/src/desert/_fields.py#L186-L193

class FromObjectProtocol(typing_extensions.Protocol):
    def __call__(self, value: object) -> HintTagField:
        ...


class FromTagProtocol(typing_extensions.Protocol):
    def __call__(self, tag: str) -> HintTagField:
        ...

Once configured, the registry needs to be able to process either an object to be serialized (.from_object() / FromObjectProtocol) or a tag (.from_tag()/ FromTagProtocol). The result must be a HintTagField which provides the calling field with the .field and .tag attributes for serialization and just the .field attribute for deserialization.

• I think that HintTagField.hint may be used only in the registry implementation and not the interface so perhaps it should be adjusted to represent that. Or perhaps the two directions shouldn't even mandate the same object, though it doesn't seem immediately obviously onerous to provide a tag when deserializing.

So... the interface does not mandate a whole lot. You could satisfy it with random return values. That's certainly a bit extreme, but I had avoided thus far thinking through what weird corners people might find for oddball relationships between hints, tags, and fields.

So, now for the provided implementation, TypeAndHintFieldRegistry. It does still have some heuristics so I'm not certain it breaks down to a simple formal mathematical mapping etc. .from_object() (for serialization) iterates over its HintTagFields and gives points to each based on:

• typeguard.check_type() against the hint
• an isinstance() check against the hint
• comparison of the object's type against the hint's typing_inspect.get_origin(), just for disambiguation

So I guess for now it is using just the hint to resolve a given object to a field and tag.

.from_tag() is straightforward, which is of course the entire point of a tagging to begin with... Only one HintTagField is allowed with a given tag and so any tag directly maps to a single HintTagField, of which only the field is used in deserialization presently.

So I guess the summary of my self-reacquaintance with this code is that the present implementation in TypeAndHintFieldRegistry selects a field/tag pair based on a hint for serialization and for deserialization it takes a tag and selects a field.

Thanks, I'm starting to get the picture.